Separate parameters list with blank lines #533
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
When there were multiple parameters with longer descriptions, the Parameters section ended up looking like a wall of text. Separating each parameter with a blank line makes it easier to read and faster to find the information you're searching for. This format is also easier for the collaborators to work with because they don't need to remember to add the ` +` at the end of the line. There are currently several reference pages where that was forgotten. I had also considered formatting the parameters section as a list. That looks quite nice also, but in the end I decided I slightly preferred the blank lines. Example of the previous formatting being problematic: https://www.arduino.cc/reference/en/language/functions/external-interrupts/attachinterrupt#_parameters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When there were multiple parameters with longer descriptions, the Parameters section ended up looking like a wall of text. Separating each parameter with a blank line makes it easier to read and faster to find the information you're searching for.
This format is also easier for the collaborators to work with because they don't need to remember to add the
+at the end of the line. There are currently several reference pages where that was forgotten.This is a proposal to change the official reference style guide. If accepted, I will update the formatting of all reference pages accordingly.
I had also considered formatting the parameters section as a list. That looks quite nice also, but in the end I decided I slightly preferred the blank lines.
Example of the previous formatting being problematic:
https://www.arduino.cc/reference/en/language/functions/external-interrupts/attachinterrupt#_parameters
Before:
After:
